=====================
Docutils HTML writers
=====================

.. note:: This document is a working draft. Naming of writers, aliases, and
   front-ends may change before the release of Docutils 0.13.

.. contents::

Overview
--------

* `Generic HTML writers`_

  =========== ============== ============== ================= ===========
  name        alias(es)      `front-end`_   HTML version      CSS version
  =========== ============== ============== ================= ===========
  html4css1_  html4          rst2html4.py   `XHTML 1          `CSS 1`_
                                            Transitional`_

  ..          html_          rst2html.py    `XHTML 1          `CSS 1`_
                                            Transitional`_

  html_plain_ html5_         rst2html5.py   `HTML 5`_         `CSS 3`_
  =========== ============== ============== ================= ===========

* `Special HTML writers`_

  =========== ============== ============== ================= ===========
  name        alias(es)      `front-end`_   HTML version      CSS version
  =========== ============== ============== ================= ===========
  pep_html_   ..             rstpep2html.py `XHTML 1          `CSS 1`_
                                            Transitional`_

  s5_html_    s5             rst2s5.py      `XHTML 1          `CSS 1`_
                                            Transitional`_
  =========== ============== ============== ================= ===========

* `HTML writers in the sandbox`_

  =========== ============== ============== ================= ===========
  name        alias(es)      `front-end`_   HTML version      CSS version
  =========== ============== ============== ================= ===========
  xhtml11_    xhtml,         rst2xhtml.py   `XHTML 1.1`_      `CSS 3`_
              html4strict

  html4trans_ ..             rst2html_trans `XHTML 1          no CSS
                                            Transitional`_    required
  =========== ============== ============== ================= ===========


.. _front-end: tools.html

Generic HTML writers
--------------------

html4css1
~~~~~~~~~

:aliases:    html4, html_
:front-ends: rst2html4.py, rst2html.py_
:config:     `[html4css1 writer]`_

The HTML Writer module, ``docutils/writers/html4css1.py``, started
as a proof-of-concept reference implementation. It is the first Docutils
writer and was up to release 0.13 the only official HTML writer.

The output conforms to the `XHTML 1 Transitional`_ specification. It does
not validate as `HTML 4.01 Transitional`_ due to the closing of empty tags
required in XML but not allowed in HTML 4. However, the output follows the
`HTML Compatibility Guidelines`_ for proper rendering on most HTML user
agents.

Correct rendering depends on a CSS_ style sheet. A reference style sheet,
`html4css1.css`_, is provided and used by default.

To support the `Internet Explorer` (with a market share of about 90% around
2002, the time this writer was written), documents contain some hard-coded
formatting hints and are tagged as "text/html" (instead of
"application/xhtml+xml"). [#IE]_

.. [#IE] Conformance to `CSS 2.1`_ has been added in IE 8 (2009), support
   for XHTML in IE 9 (2011).

.. TODO: How to name a specific alias/front-end pointing to html4css1?

   html4
     | +1 short form of html4css1,
     | -1 writer produces XHTML 1, not HTML 4
   xhtml1
     | +1 correct and short description of the output format.
     | -1 may be confused with xhtml11 or xhtml (aliases for the
          "new" XHTML 1.1. writer inheriting from html_plain).


.. _rst2html.py: tools.html#rst2html-py
.. _[html4css1 writer]: config.html#html4css1-writer
.. _html4css1.css: ../../docutils/writers/html4css1/html4css1.css


html_plain
~~~~~~~~~~

:aliases: html5_
:front-end: rst2html5.py_
:config: `[html-plain writer]`_

The `html_plain` module is both, basis for other HTML writers and a
versatile writer for end-users or programmatic use.

The ``html_plain`` writer generates `polyglot HTML`_ output that is
compatible with `HTML 5`_ and `XHTML 1 Transitional`_. New features and
elements will only be used if they are widely supported to make documents
`viewable with any browser`_.  There is no hard-coded formatting information
in the HTML document. Correct rendering of elements not directly supported
by HTML depends on a CSS_ style sheet. The provided style sheets
minimal.css_ and plain.css_ define required and optional styling rules
respectively. Adaption of the layout is possible with `custom style
sheets`_.

New in Docutils 0.13

.. TODO

   Find the right name for this writer. Suggestions:

   html-common
     ±0 common definitions for XHTML and HTML5
   html-plain
     ±0 simple, plain, unadorned.
   html-simple
     ±0 simple
   html-vanilla
     -0 too long, too colloquial
   html-basic
     -1 does not produce `XHTML Basic`_
   html-lcd
     `Lowest Common Denominator` -- supporting HTML 5, XHTML 1,
     and older (HTML 4 + CSS2) browsers.

     -1 cryptic
   html-base
     -1 not only base class but also suited for end-users

.. _rst2html5.py: tools.html#rst2html5-py
.. _[html-plain writer]: config.html#html-plain-writer
.. _minimal.css: ../../docutils/writers/html_plain/minimal.css
.. _plain.css: ../../docutils/writers/html_plain/plain.css
.. _custom style sheets: ../howto/html-stylesheets.html
.. _viewable with any browser: http://www.anybrowser.org/campaign

Aliases
~~~~~~~

html
""""

Currently, `html` is an alias for the html4css1_ writer.

Suggestion
  The alias `html` points to the "recommended Docutils HTML writer".
  Its target may change with the development of HTML, browsers, Docutils, and
  the web.

  * Use `get_writer_by_name('html') or the ``rst2html.py`` front end, if you
    want the output to be up-to-date automatically.

  * Use a specific writer name or front end, if you depend on stability of
    the generated HTML code, e.g. because you use a custom style sheet or
    post-processing that may break otherwise.

html4
"""""

The alias `html4` provides a stable shortcut for the html4css1_ writer.

New in Docutils 0.13

html5
"""""

In Docutils 0.13, html5 is an alias to the html_plain_ writer.

In future releases, `html5` may become a separate HTML writer that makes use
of new features and objects defined in HTML5 but not (yet) fit for use in
`html_plain`_ because of limited browser support (like <video>, <aside>, or
<section>).

Special HTML writers
--------------------

pep_html
~~~~~~~~

:front-end: rstpep2html.py_
:config:    `[pep_html writer]`_

This is a special writer for the generation of `Python Enhancement
Proposals`_ (PEPs). It inherits from html4css1_ and adds some `PEP-specific
options`_, a style sheet and template. The front-end uses also a specialised
reader.

.. _rstpep2html.py: tools.html#rstpep2html-py
.. _PEP-specific options:
.. _[pep_html writer]: config.html#pep-html-writer
.. _Python Enhancement Proposals: https://www.python.org/dev/peps/

s5_html
~~~~~~~

:alias:     s5
:front-end: rst2s5.py_
:config:    `[s5_html writer]`_

The `s5` writer inherits from html4css1_. It produces XHTML for use with
S5_, the “Simple Standards-based Slide Show System” by Eric Meyer.  See
`Easy Slide Shows With reST & S5`_ for details.

.. _rst2s5.py: tools.html#rst2s5-py
.. _[s5_html writer]: config.html#s5-html-writer
.. _Easy Slide Shows With reST & S5: slide-shows.html
.. _S5: http://meyerweb.com/eric/tools/s5/
.. _theme: tools.html#themes


HTML writers in the sandbox
---------------------------

There are two more HTML writers in the sandbox_:

xhtml11
~~~~~~~
:aliases:   xhtml, html4strict
:front-end: rst2xhtml.py
:config:    `[xhtml11 writer]`

`XHTML 1.1`_ is the current version of the XML based `extensible Hypertext
Markup Language`.

The `xhtml11` writer inherits from html_plain_ and adds compatibility to the
strict requirements of `XHTML 1.1`_:

* There is no attribute "lang" (only "xml:lang").

* Enumerated lists don't support the 'start' attribute.

  The style sheet xhtml11.css_ adds support for a "start" value for
  enumerated lists via a CSS-counter. This allows also nested enumeration.

* ``<sup>`` and ``<sub>`` tags are not allowed in preformatted blocks
  (``<pre>``).

The `math-output` `config setting`_ defaults to "MathML".

.. _sandbox: ../dev/policies.html#the-sandbox
.. _rst2xhtml.py: tools.html#rst2html5-py
.. _config setting:
.. _[xhtml11 writer]: config.html#xhtml11-writer
.. _xhtml11.css: ../../docutils/writers/xhtml11/xhtml11.css


html4trans
~~~~~~~~~~

:front-end: rst2html_trans.py_

The `HTML writer for lightweight browsers`_ lives in the Docutils sandbox
(`sandbox/html4trans`_) since 2008. It removes the dependency on CSS. The
output conforms to `XHTML 1 Transitional`_ and contains sufficient
formatting information for rendering without style sheet. (Of course, this
has some drawbacks_.)

.. _HTML writer for lightweight browsers:
   ../../../sandbox/html4trans/README.html
.. _drawbacks: ../../../sandbox/html4trans/README.html#drawbacks
.. _sandbox/html4trans: ../../../sandbox/html4trans
.. _rst2html_trans.py: ../../../sandbox/html4trans/tools/rst2html_trans.py


HTML and CSS Versions
---------------------

_`HTML 5`
   `HTML5, A vocabulary and associated APIs for HTML and XHTML`,
   W3C Recommendation, 28 October 2014.
   http://www.w3.org/TR/html5/

_`XHTML 1.1`
   `XHTML™ 1.1 - Module-based XHTML - Second Edition`,
   W3C Recommendation, 23 November 2010.
   http://www.w3.org/TR/xhtml11/

_`XHTML 1 Transitional`
   `Transitional version`_ of:
   `XHTML™ 1.0 The Extensible HyperText Markup Language (Second
   Edition)`, `A Reformulation of HTML 4 in XML 1.0`,
   W3C Recommendation, 26 January 2000, revised 1 August 2002.
   http://www.w3.org/TR/xhtml1/

_`XHTML Basic`
   `XHTML™ Basic 1.1 - Second Edition`,
   W3C Recommendation, 23 November 2010.
   http://www.w3.org/TR/xhtml-basic/

.. _transitional version:
   http://www.w3.org/TR/xhtml1/#a_dtd_XHTML-1.0-Transitional

_`HTML 4.01 Transitional`
  Transitional version of:
  `HTML 4.01 Specification`, W3C Recommendation 24 December 1999.
  http://www.w3.org/TR/html4/

.. _`CSS 1`:

_`CSS Level 1`:
  The features defined in the CSS1 specification, but using the syntax
  and definitions in the `CSS 2.1`_ specification.

_`CSS 2.1` `Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification`,
  W3C Recommendation 07 June 2011.
  http://www.w3.org/TR/CSS21/

_`CSS 3`:
  CSS Level 3 builds on CSS Level 2 module by module, using the CSS2.1
  specification as its core.

  Specifications: http://www.w3.org/Style/CSS/specs.en.html

  Validator: http://jigsaw.w3.org/css-validator/

.. other references
   ----------------

.. _HTML Compatibility Guidelines: http://www.w3.org/TR/xhtml1/#guidelines
.. _polyglot HTML: http://www.w3.org/TR/html-polyglot/
.. _CSS: http://www.w3.org/TR/CSS/
